Appendix : Placeholders

Placeholders

One of the most powerful features of DEVONthink is the ability to insert data dynamically. A placeholder is a bit of code DEVONthink interprets when used in these scenarios, replacing it with a specific value. You may have an imprint with a Name placeholder defined in the title. When the imprint is used on a PDF, the placeholder is converted to the name of the file!

To extend the possibilities even further, you can combine static text and multiple placeholders to achieve truly custom results. You can use these in smart rules and the command Tools > Batch Process, in alarms on Reminders, custom imprints on images and PDFs, and in templates for creating WikiLinks documents. However, please be aware not all placeholders can be used in all those situations. For example, you can't use the Location placeholder in a template as the document doesn't have a location until after it's created. Testing is strongly encouraged.

Below is a list of placeholders currently available. Following each description is the raw placeholder that can be used when creating templates in external application or using the import template AppleScript command:

Name: The name or title of the document. %recordName%
Proposed Name: A suggested name derived from a document's title or from the first line of the document if no title is present. %recordProposedName%
Name Without Date: Returns the filename after parsing out any detected dates. %recordNameWithoutDate%
Aliases: Any aliases applied to the document. %recordAliases%
Finder Comment: Any Finder comments applied to the document. %recordComment%
File Name: The filename in the file system. %recordFilename%
File Extension: The extension of the document's filename. %recordPathExtension%
Kind: The kind of the file, e.g., group or rich text document. %recordKind%
URL: The URL in the Info pane. %recordURL%
Item Link: The unique URL of the document. %recordLink%
Location: The location in the database; e.g., /Inbox/Research. %recordLocation%
Tags: Tags applied to the document. %recordTags%
#Tags: Tags applied to the document but returned as hashtags. %recordHashTags%

Index: This is a number that increments based on the number of items being processed by a smart rule. %recordIndex%
Counter: Similar to the Index, this is a zero-padded incrementing number. %recordCounter%
Document Amount: This is an amount detected in the name or content of documents, like receipts or invoices. Often used with smart rules. %documentAmount%
Document String: This is a string detected in the name or content of documents. Typically used with smart rules. %documentString%
Digital Object Identifier: The unique digital object identifier of the active document, if available. %digitalObjectIdentifier%
Bates Number: Inserts a Bates number. %recordBatesNumber%
Page Count: The total number of pages in the document. %recordPageCount%

Group Name: The name of the group containing the document, e.g., /001/a/b/myfile.txt would report b as the group name. %groupName%
Top Group Name: The name of the top level group in the root of the database, e.g., /001/a/b/myfile.txt would report 001 as the top group name. %topGroupName%
Database Name: The name of the database containing the document. %databaseName%
Database Path: The filesystem path of the database. %databasePath%

Attachments: The number of attachments in a document, e.g., a rich text document or email. %record_attachments%
PDF Annotations: The number of annotations in the active document. %record_annotationcount%
Incoming Item Links: The number of documents containing item links to the active document. %record_incomingItemLinkCount%
Outgoing Item Links: The number of documents linked to in the active document. %record_outgoingItemLinkCount%
Language: An abbreviation of language detected in the document's indexed contents. %record_language%
Country: The country in the geolocation data for a document. %record_country%
Postal Code: The postal code derived from the geolocation data for a document. %record_zipcode%
Administrative Area: This is state, province, or region in the geolocation data for a document. %record_area%
Locality: The city in the geolocation data for a document. %record_locality%

Tab: A tab character. %tab%
Line Break: A line break (return) character for multi-line text. %newline%

Date Placeholders: There are several types of date-specific placeholders to choose from. You can choose from several built-in formats, e.g., the short date, or create your own with individual date component placeholders. Due to the repetition of date placeholders, the raw value of every individual placeholder isn't listed here. However, below are the date component raw values. Note some formats will resolved relative to your geographic location, e.g., Jan 1, 2001 for the medium date would be common in the US.

01/01/2001: The short date format. %shortDate%
Jan 1, 2001: The medium date format. %date%.
2001/01/01: The ISO date format. %sortableDate%
Saturday, Jan 1, 2001: The long date format. %longDate%
11:59:59 AM: The current time shown in 12 or 24 hour format, depending on your system settings. %time%
12 hours, 43 minutes, and 12 seconds: A custom time format made with text and the following placeholders. %hour%, %minute%, and %second%
01: The zero-padded number of the date. %day%
Saturday: The name of the day. %weekday%
01: The zero-padded number of the month. %month%
January: The name of the month. %monthname%
2001: The full year. %year%
01: The short year. %shortYear%

Listed below are the supported date types with their raw value provided. Prefix the raw value with a date component as shown in the example below.

Example:

%newestDocumentDateLongDate%

Current Date: Today's date. There is no prefix to the raw placeholders for current date.
Addition Date: The date the item added to the database. recordAddition…
Creation Date: The date the item was created. recordCreation…
Modification Date: The date the items was last modified. recordModification…
Document Date: This is a date detected in the document's contents, e.g., in a receipt. For PDFs only the first four pages are used. documentDate…
Newest/Oldest Document Date: The newest or oldest date detected in the document. For PDFs, only the first four pages are used. newestDocumentDate… and oldestDocumentDate…

Note: When using the raw values for the date types, e.g., modification date, note the date component's raw value will start with a capital letter. For example, use %recordCreationShortDate% not "%recordCreationshortdate%".

Clipboard: Inserts plain text content from the clipboard. %clipboard%
Clipboard Styled: Inserts rich text content from the clipboard. %styledClipboard%
Clipboard Link: Inserts a link from rich text content on the clipboard. %clipboardLink%
Predefined Author: This is the Author specified in DEVONthink's Settings > Editing. %author%
Username: The shortname of the current macOS account. %username%
Full Username: The longname of the current macOS account. %fullUsername%
Organization: This is the company name, if defined by the (Me) contact card in macOS Contacts. %organization%
Email Address: The primary email address, as defined by the (Me) contact card in macOS Contacts. %emailAddress%
Host: The hostname of the machine. %host%

Properties: Some files have specific properties, e.g., the author of an email. These are displayed in the Info > Properties inspector. Here are properties with supported placeholders with their raw value.

Author: The name of the sender of an email. %kMDItemAuthors%
From: The email address of the sender of an email. %kMDItemAuthorEmailAddresses%
Recipient: The name of a recipient of an email. %kMDItemRecipients%
To: The email address of a recipient of an email. %kMDItemRecipientEmailAddresses%
E-mail: Email addresses detected in a document. %kMDItemEmailAddresses%
Title: The title of a file. The title may be distinct from its name, e.g., a song title for an MP3 file. %kMDItemTitle%
Comment: The RTF-specific comments for a file. %kMDItemComment%
Headline: A headline applied to some files. Rare. %kMDItemHeadline%
Subject: The subject line from an email. %kMDItemSubject%
Description: The description found on some files, typically images. %kMDItemDescription%
Keywords: Keywords typically applied to PDF, rich text, or images. %kMDItemKeywords%
Organization: The company specified in imported links or vCards from the Contacts application. %kMDItemOrganizations%
Copyright: Copyright information in the metadata of a file. %kMDItemCopyright%
Album: The album information from media metadata, e.g., MP3 files. %kMDItemAlbum%
Composer: The composer information from media metadata, e.g., MP3 files. %kMDItemComposer%
Creator: The process or application used to create a file. %kMDItemCreator%
Producer: The producer of a file, usually applied to media files. %kMDItemProducer%

A more extensive listing other types of metadata can be found in the Metadata section of this appendix.

Custom Metadata: This menu lists any custom metadata attributes you've defined in the Data settings. In order to use raw placeholders, add the md prefix to the identifier of the custom attribute shown in the settings. For example, mddoi for the Digital Object Identifier attribute.